Making an Academic Website

Elissa Berwick

McGill University

February 9, 2024

Agenda


  1. Elements of an academic website
  2. No-coding methods
  3. Quarto for academic websites
    • Getting started with Quarto
    • Publishing with GitHub Pages
    • Advanced content and customization

Website elements

Landing page

Introduce and define yourself

  • Provide current position and educational background
  • Identify what field(s) you work in

Separate “About” page

  • A separate “About” page can provide more detail

Single “Home” page

  • Or a single “Home” page can have everything

Research

Information on publications AND current projects

  • Include summaries or keywords for papers
  • Link to PDFs and/or add replication files

Teaching

Describe your teaching experience

  • Detail your approach to teaching

Teaching

Describe your teaching experience

  • Add teaching resources you’ve developed

Extras

Make it interesting!

  • Share projects

Extras

Make it interesting!

  • Share a blog

Extras

Make it interesting!

  • Add photos and hobbies

No-coding methods

Pre-made templates

  • Powerpoint-like experience
  • Designed by professionals

Template providers

  • Pricing (CAD) for basic plan that includes domain name (i.e. yourname.com)

    • WordPress: from $5/month
    • Weebly: from $7/month
    • GoDaddy: from $12/month
    • Wix: from $15/month
    • Squarespace: $21/month
  • Design quality and inclusions are proportional to price!

  • WordPress and Weebly have free options without custom domain

  • GitHub is free with domain name username.github.io
    … but requires coding

Custom domain names

  • You can purchase a domain name directly from the last slide’s website template providers

  • OR you can purchase a domain separately from a domain registrar

    • Keeps your ownership of the domain independent of your current template
  • Options include:

    • GoDaddy (largest)
    • Domain.com
    • Google Domains (easiest)
    • Cloudflare

Getting started with Quarto

Why use Quarto?

  • Three building blocks of a website:

    • Basic structure built with html
    • Styling done with css
    • Dynamic content from JavaScript (not needed for a static site)
  • Static site generators: convert easy-to-write Markdown to html for use in a static website

    • Examples: Jekyll, Hugo, Gatsby
  • There are other R packages like distill and blogdown that let you do this too

    • Quarto is a new Markdown based way to generate static webite content

What is Quarto?

  • RMarkdown beyond R (support for Python, Julia, Observable)
  • Output types (via pandoc):
    • PDF (via LaTeX)
    • MS Word
    • Revealjs
    • PowerPoint
    • Beamer
    • Markdown
    • HTML

Project setup

Create a new project in RStudio

  • Select “new project” from upper right corner of GUI

  • Select “new directory”

  • Select “Quarto website”

  • Give the directory a name

    • This will be the name of the GitHub repository as well
    • If you plan on hosting the page on GitHub, make sure you name the project/repository username.github.io
  • Pick somewhere to save the entire project

What’s in the project?

You will now have a folder with several (mostly blank) files:

  • _quarto.yml: config file with common yaml information for all the pages in your site

    • Includes title, navbar contents, theme
  • styles.css: where you can put design settings written in css

    • css (“cascading style sheets”) are the main styling system for the entire internet
    • Holds custom design elements like colors and fonts
    • Note: you’ll probably want to use scss (Sass) for customization instead!

What’s in the project?

You will now have a folder with several (mostly blank) files:

  • index.qmd: your site’s landing page

    • This is where you’ll put content to display when someone first arrives on your site
    • Don’t change the name!
  • about.qmd: an initial page on your site

    • You can copy and rename this demo page as needed

Editing yaml

  • Change the site title to your name
project:
  type: website

website:
  title: "My Name"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
  • You can also move the navbar to the right or turn off the table of contents

Rendering

You already have the basics for a site!

  • Click Build > Render Website to convert all of your quarto files into html output in the docs folder

    • Button is in the pane with Environment, History, Git, etc.
  • A preview version should open up in RStudio

    • The site isn’t live yet, this is just a local preview version!
    • To make it live we will deploy via GitHub Pages (to be continued…)
    • You can also use another service like Netlify

Themes: options

  • You can change the appearance of your site to one of the pre-made “Bootswatch” themes (css someone else already wrote)

    • A random selection:
      • cosmo
      • lux
      • minty
      • slate
      • yeti
      • zephyr

Themes: trying it out

  • Try setting theme: zephyr or another theme of your choice
project:
  type: website

website:
  title: "My Name"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: zephyr
    css: styles.css
    toc: true
  • Render site to preview

Page content: Markdown

  • You can use Markdown syntax to edit your landing page

  • For example:

    • Use # for top-level headers, ## for second-level headers etc.
    • Bullet points with -
    • Numbered lists with 1. etc
    • Links: [text](https://link.com)
    • Images: ![Caption](project_directory/folder/image)1

Page content: Markdown

  • Try adding an introduction in Markdown to your site and rendering it
## Lorem Ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

- Sed at nulla lobortis, faucibus nisi et, tempor dui. 
- Fusce quis nulla sodales, ultricies arcu vitae, bibendum est. 

Donec neque justo, vulputate vel velit ut, pulvinar suscipit nibh.

1. Nullam risus erat, consectetur quis libero in, condimentum accumsan quam.

Maecenas egestas pulvinar lobortis.

Page content: “About” pages

  • For easier layout options, make pages into “About” pages

  • To do this, you will add an about option to the yaml of the page you want to change (not _yaml.qmd!)

  • You will need to pick one of 5 templates for your About page:

    • jolla
    • trestles
    • solana
    • marquee
    • broadside

About pages: trying it out

  • Try making index.qmd an “About” page using template: jolla
---
title: "Finley Malloc"
about:
  template: jolla
  image: profile.jpg
  links:
    - icon: github
      text: Github
      href: https://github.com
    - icon: file-pdf
      text: CV
      href: my_cv.pdf  
---

About pages: trying it out

  • Add a picture of yourself using image: profile.jpg
  • You can also add links to social media, GitHub or files like your CV1
---
title: "Finley Malloc"
about:
  template: jolla
  image: profile.jpg
  links:
    - icon: github
      text: Github
      href: https://github.com
    - icon: file-pdf
      text: CV
      href: my_cv.pdf  
---

Make a new page

  • You can make new pages by creating new .qmd files in the project directory

  • Try making a new quarto file called research.qmd1

  • You can add content using Markdown as before

    • Tip: you can also format any page (or part of a page) using one of the “About” templates

Add it to the site

  • Add your new page to the site by linking it to the navbar in the _quarto.yaml file
project:
  type: website
  output-dir: docs

website:
  title: "My Name"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - research.qmd  

format:
  html:
    theme: zephyr
    css: styles.css
    toc: true

Publishing with GitHub Pages

Project setup

In your RStudio project:

  • Open the file _quarto.yml and set output-dir: docs
project:
  type: website
  output-dir: docs
  
website:
  title: "My Name"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - research.qmd  
  • Add an empty text file to the project directory and name it .nojekyll

  • Render site using Build > Render Website

GitHub setup (manual)

  • Create a repository in your GitHub account that has the same name as your RStudio project

  • From within the new repository, select Add file > Upload files and upload the entire contents of the project directory

  • Every time you want to edit your site you will need to:

    1. Build > Render Website
    2. Upload all new files to GitHub

git and RStudio

  • Haven’t used git directly from RStudio before?

    • You will need to generate a PAT using usethis::create_github_token()
    • Store it in RStudio using gitcreds::gitcreds_set()

GitHub setup (usethis)

  • Set up your project for git tracking by running usethis::use_git()

  • Create a corresponding repository on GitHub by running usethis::use_github()

  • Every time you want to edit your site you will need to:

    1. Build > Render Website
    2. Stage files by checking names in Git tab
    3. Commit files by clicking Commit and adding a message
    4. Push to the repository by clicking Push

GitHub Pages setup

In the repository page on github.com:

  • Go to the “Settings” tab in the top menu bar

  • Then select “Pages” from the left menu bar

  • Set branch to main or master1 and selected folder to /docs and save

  • The url will change when the page is fully deployed

  • Go to the “Actions” tab in the top menu bar to see the deployment status

Advanced content and customization

Page content: pandoc

  • Markdown is supposed to be easy to read
  • For more complex formats, you can use pandoc syntax
  • Try adding columns using a .columns div
Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

::: {.columns}
::: {.column width="50%"}
Sed at nulla lobortis, faucibus nisi et, tempor dui. 
:::

::: {.column width="50%"}
Fusce quis nulla sodales, ultricies arcu vitae, bibendum est.
:::
:::

Custom styles

  • Want to customize colors, fonts, and more? Use Sass!

    • Tip: Add customization on top of an existing theme by using multiple theme arguments
      • ex: theme: [journal, styles.scss]
  • How:

    • Make a new file ending in .scss and add it to the theme setting in your _yaml.qmd file
    • Make two sections in your new file:
      • /*-- scss:defaults --*/
      • /*-- scss:rules --*/

Defaults

  • Define variables like colors and fonts in scss:defaults
/*-- scss:defaults --*/

// import a font from google
@import url('https://fonts.googleapis.com/css2?family=Merriweather&display=swap');

// set fonts for text
$font-family-sans-serif: "Merriweather", Palatino, FreeSerif, serif !default;

// document colors
$body-bg: #181818;
$body-color: white;
$link-color: #75AADB;

// code blocks
$code-block-bg-alpha: -.8;

Rules

  • Use scss:rules to define additional css styles
/*-- scss:rules --*/

// highlight a word
.highlight {
  color: #D33582;
  font-weight: bold;
}
 
  • To use this style, you would type:
    [highlighted phrase]{.highlight}

  • Which would produce: highlighted phrase

Resouces